Конфігурація TypeScript: вичерпний посібник з tsconfig.json

TypeScript, розширений набір JavaScript, привносить статичну типізацію у динамічний світ веб-розробки. Правильно налаштований файл tsconfig.json є вирішальним для використання повної потужності TypeScript. Цей посібник надає вичерпний огляд tsconfig.json, охоплюючи основні параметри компілятора, налаштування проєкту та розширені конфігурації.

Що таке tsconfig.json?

Файл tsconfig.json — це конфігураційний файл, який визначає параметри компілятора для проєкту TypeScript. Він вказує компілятору TypeScript, як транспілювати код TypeScript у JavaScript. Цей файл є ключовим для визначення структури проєкту, встановлення правил компіляції та забезпечення узгодженості в команді розробників, незалежно від того, чи знаходиться команда в одному офісі, чи розподілена по різних континентах.

Створення файлу tsconfig.json

Щоб створити файл tsconfig.json, перейдіть до кореневого каталогу вашого проєкту в терміналі та виконайте таку команду:

            tsc --init
            

              
                Copy
              
            
          

Ця команда генерує базовий файл tsconfig.json з часто використовуваними параметрами компілятора. Потім ви можете налаштувати файл відповідно до конкретних вимог вашого проєкту. Типовий tsconfig.json міститиме такі опції, як compilerOptions, include та exclude.

Основні параметри компілятора

Секція compilerOptions є серцем файлу tsconfig.json. Вона містить широкий спектр опцій, які керують поведінкою компілятора TypeScript. Ось деякі з найважливіших параметрів компілятора:

target

Опція target визначає цільову версію ECMAScript для згенерованого коду JavaScript. Поширені значення включають ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Вибір правильної цілі є вирішальним для забезпечення сумісності з призначеним середовищем виконання, таким як браузери або версії Node.js.

Приклад:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

Опція module визначає стиль генерації коду модулів. Поширені значення включають CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 та ESNext. Вибір системи модулів залежить від цільового середовища та використовуваного збирача модулів (наприклад, Webpack, Rollup, Parcel). Для Node.js часто використовується CommonJS, тоді як для сучасних веб-додатків перевага надається ES6 або ESNext зі збирачем модулів. Використання ESNext дозволяє розробникам використовувати найновіші функції та оптимізації, покладаючись на збирач для обробки кінцевого формату модуля.

Приклад:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

Опція lib визначає список файлів бібліотек, які будуть включені в компіляцію. Ці файли бібліотек надають визначення типів для вбудованих API JavaScript та API браузера. Поширені значення включають ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String та багато інших. Вибір відповідних бібліотек гарантує, що компілятор TypeScript має необхідну інформацію про типи для цільового середовища. Використання бібліотеки DOM дозволяє проєкту компілювати код, який використовує специфічні для браузера API без помилок типів.

Приклад:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

Опція allowJs дозволяє компілятору TypeScript компілювати файли JavaScript разом із файлами TypeScript. Це корисно для поступової міграції існуючих проєктів JavaScript на TypeScript. Встановлення цього значення на true дозволяє компілятору обробляти файли .js, що уможливлює поступове впровадження TypeScript у проєкті.

Приклад:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

Опція jsx визначає, як слід обробляти синтаксис JSX. Поширені значення включають preserve, react, react-native та react-jsx. preserve зберігає синтаксис JSX у вихідному файлі, тоді як react перетворює JSX у виклики React.createElement. react-jsx використовує нове перетворення JSX, представлене в React 17, яке не вимагає імпорту React. Вибір правильної опції JSX є вирішальним для проєктів, що використовують React або інші бібліотеки на основі JSX.

Приклад:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

Опція declaration генерує відповідні файли декларацій .d.ts для кожного файлу TypeScript. Файли декларацій містять інформацію про типи і використовуються іншими проєктами TypeScript для споживання скомпільованого коду. Генерація файлів декларацій є важливою для створення бібліотек і модулів для повторного використання. Ці файли дозволяють іншим проєктам TypeScript розуміти типи та інтерфейси, що надаються бібліотекою, без необхідності компілювати вихідний код.

Приклад:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

Опція sourceMap генерує файли карт вихідного коду (source maps), які зіставляють згенерований код JavaScript з оригінальним кодом TypeScript. Карти вихідного коду є важливими для налагодження коду TypeScript у браузерах та інших середовищах. Коли в коді JavaScript виникає помилка, карта вихідного коду дозволяє розробнику побачити відповідний код TypeScript у налагоджувачі, що полегшує виявлення та виправлення проблеми.

Приклад:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

Опція outDir вказує вихідний каталог для згенерованих файлів JavaScript. Ця опція допомагає організувати вихідні дані збірки проєкту, відокремлюючи вихідний код від скомпільованого. Використання outDir полегшує керування процесом збірки та розгортання програми.

Приклад:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

Опція rootDir вказує кореневий каталог проєкту TypeScript. Компілятор використовує цей каталог як основу для розв'язання імен модулів. Ця опція особливо важлива для проєктів зі складною структурою каталогів. Правильне налаштування rootDir гарантує, що компілятор зможе знайти всі необхідні модулі та залежності.

Приклад:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

Опція strict вмикає всі опції суворої перевірки типів. Це настійно рекомендується для нових проєктів TypeScript, оскільки це допомагає виявляти потенційні помилки на ранніх етапах процесу розробки. Увімкнення суворого режиму забезпечує більш жорсткі правила перевірки типів, що призводить до більш надійного та підтримуваного коду. Найкращою практикою є ввімкнення суворого режиму у всіх нових проєктах TypeScript.

Приклад:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

Опція esModuleInterop забезпечує сумісність між модулями CommonJS та ES. Це важливо для проєктів, які використовують обидва типи модулів. Коли esModuleInterop увімкнено, TypeScript автоматично обробляє відмінності між модулями CommonJS та ES, що полегшує імпорт та експорт модулів між двома системами. Ця опція особливо корисна при роботі зі сторонніми бібліотеками, які можуть використовувати різні системи модулів.

Приклад:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

Опція moduleResolution визначає, як TypeScript розв'язує імпорти модулів. Поширені значення включають Node та Classic. Стратегія розв'язання модулів Node є стандартною і базується на алгоритмі розв'язання модулів Node.js. Стратегія розв'язання модулів Classic є старішою і використовується рідше. Використання стратегії розв'язання модулів Node гарантує, що TypeScript зможе правильно розв'язувати імпорти модулів у середовищі Node.js.

Приклад:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl та paths

Опції baseUrl та paths використовуються для налаштування розв'язання модулів для невідносних імпортів. Опція baseUrl визначає базовий каталог для розв'язання невідносних імен модулів. Опція paths дозволяє зіставляти імена модулів з конкретними місцями у файловій системі. Ці опції особливо корисні для проєктів зі складною структурою каталогів та для спрощення імпортів модулів. Використання baseUrl та paths може зробити код більш читабельним та підтримуваним.

Приклад:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Опції Include та Exclude

Опції include та exclude визначають, які файли слід включити в компіляцію, а які — виключити. Ці опції використовують шаблони glob для зіставлення імен файлів. Використання include та exclude дозволяє контролювати, які файли обробляються компілятором TypeScript, покращуючи продуктивність збірки та зменшуючи кількість помилок. Найкращою практикою є явне вказування файлів, що підлягають компіляції.

Приклад:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Опція Extends

Опція extends дозволяє успадковувати параметри компілятора з іншого файлу tsconfig.json. Це корисно для спільного використання загальних налаштувань конфігурації між кількома проєктами або для створення базових конфігурацій. Використання опції extends сприяє повторному використанню коду та зменшує дублювання. Найкращою практикою є створення базових конфігурацій та їх розширення в окремих проєктах.

Приклад:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Розширені конфігурації

Крім основних параметрів компілятора, tsconfig.json підтримує розширені конфігурації для спеціалізованих сценаріїв.

Інкрементальна компіляція

Для великих проєктів інкрементальна компіляція може значно скоротити час збірки. TypeScript може кешувати результати попередніх компіляцій і перекомпілювати лише ті файли, які були змінені. Увімкнення інкрементальної компіляції може значно скоротити час збірки для великих проєктів. Це особливо важливо для проєктів з великою кількістю файлів та залежностей.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Посилання на проєкти

Посилання на проєкти (Project references) дозволяють структурувати великі проєкти TypeScript на менші, незалежні модулі. Це може покращити час збірки та організацію коду. Використання посилань на проєкти може зробити великі проєкти більш керованими та легшими для підтримки. Найкращою практикою є використання посилань на проєкти для великих, складних проєктів.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Користувацькі визначення типів

Іноді вам може знадобитися надати визначення типів для бібліотек JavaScript, які їх не мають. Ви можете створити власні файли .d.ts для визначення типів для цих бібліотек. Створення користувацьких визначень типів дозволяє використовувати бібліотеки JavaScript у вашому коді TypeScript без шкоди для безпеки типів. Це особливо корисно при роботі зі старим кодом JavaScript або бібліотеками, які не надають власних визначень типів.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Найкращі практики

• Використовуйте суворий режим: Увімкніть опцію strict для посиленої перевірки типів.
• Вказуйте ціль: Оберіть відповідну версію target для вашого середовища виконання.
• Організовуйте вихідні файли: Використовуйте outDir для відокремлення вихідного коду від скомпільованого.
• Керуйте залежностями: Використовуйте include та exclude для контролю над тим, які файли компілюються.
• Використовуйте Extends: Діліться загальними налаштуваннями конфігурації за допомогою опції extends.
• Зберігайте конфігурацію в системі контролю версій: Додавайте `tsconfig.json` до git для підтримки узгодженості між середовищами розробників та конвеєрами CI/CD.

Вирішення поширених проблем

Налаштування tsconfig.json іноді може бути складним. Ось деякі поширені проблеми та їх вирішення:

Проблеми з розв'язанням модулів

Якщо ви стикаєтеся з помилками розв'язання модулів, переконайтеся, що опція moduleResolution налаштована правильно, і що опції baseUrl та paths встановлені належним чином. Двічі перевірте шляхи, вказані в опції paths, щоб переконатися, що вони правильні. Перевірте, чи всі необхідні модулі встановлені в каталозі node_modules.

Помилки типів

Помилки типів можуть виникати, якщо визначення типів неправильні або відсутні. Переконайтеся, що у вас встановлені правильні визначення типів для всіх бібліотек, які ви використовуєте. Якщо ви використовуєте бібліотеку JavaScript, яка не має визначень типів, розгляньте можливість створення користувацьких визначень типів.

Помилки компіляції

Помилки компіляції можуть виникати, якщо у вашому коді TypeScript є синтаксичні помилки або помилки типів. Уважно перегляньте повідомлення про помилки та виправте будь-які синтаксичні помилки або помилки типів. Переконайтеся, що ваш код відповідає угодам кодування TypeScript.

Висновок

Правильно налаштований файл tsconfig.json є важливим для успішного проєкту TypeScript. Розуміючи основні параметри компілятора та розширені конфігурації, ви можете оптимізувати свій робочий процес розробки, покращити якість коду та забезпечити сумісність з цільовим середовищем. Інвестування часу в правильне налаштування tsconfig.json окупиться в довгостроковій перспективі, зменшивши кількість помилок, покращивши підтримуваність та оптимізувавши процес збірки. Це призводить до більш ефективної та надійної розробки програмного забезпечення. Інформація, надана тут, розроблена так, щоб бути універсально застосовною, і повинна забезпечити міцну основу для початку нового проєкту з TypeScript.

Не забувайте звертатися до офіційної документації TypeScript для отримання найактуальнішої інформації та детальних пояснень усіх доступних параметрів компілятора. Документація TypeScript є цінним ресурсом для розуміння тонкощів конфігурації TypeScript.